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ABSTRACT 


EDIT  is  a MACRO  program  for  automatic  maintenance 
of  FORTRAN  and  RATFOR  (Rational  FORTRAN)  programs  on 
the  Texas  Instruments  Advanced  Scientific  Computer. 

It  has  been  used  extensively  to  accelerate  the 
creation  of  complex  fluid  dynamics  programs  for  execu- 
tion on  the  Advanced  Scientific  Computer  (ASC) . 

EDIT  allows  the  user  to  more  efficiently  create 
and  modify  programs  using  the  TI -supplied  Source 
Management  System,  SMS.  Object  libraries  and  load 
modules  may  also  be  automatically  updated.  The  program 
files  (source,  object,  and  load  module)  have  a user- 
specified  number  of  versions  retained  as  backup.  The 
files  may  be  tape  or  disk  resident.  The  EDIT  system 
is  described  and  sample  usages  are  presented. 


INTRODUCTION 

The  Texas  Instruments  Advanced  Scientific  Computer  (ASC)  is  a large- 
scale  digital  computer  which  was  installed  at  the  Naval  Research 
Laboratory  in  April  1976.  Its  vector  arithmetic  capability  and  massive 
central  memory  make  it  attractive  for  use  in  solving  large  numerical 
problems.  While  the  ASC  was  being  used  to  develop  involved  fluid  mechanics  i 

programs,  the  need  for  some  procedure  to  automatically  update  programs 
became  apparent.  This  deficiency  led  to  the  development  of  a MACRO 
program,  EDIT,  which  generates  the  control  cards  a user  needs  to  update  a 
program  library.  One  EDIT  call  card  and  a set  of  Texas  Instruments 
Source  Management  System  directives  (SMS  manuals  are  available  from  NRL 
Code  4222)  allow  a programmer  to  perform  a program  update  which,  if  done 
manually,  would  require  approximately  80  control  cards. 

EDIT  was  modeled  on  a similar  program  used  on  the  CDC  6000  computers 

at  DTNSRDC.  This  program,  also  called  EDIT,  was  developed  by  Mel  Haas  of 
DTNSRDC,  Code  1843,  in  1972. 
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DESCRIPTION 


The  EDIT  macro  utilizes  Tl-supplied  software  (eg.,  SMS,  CIFER,  FTN, 
PDSQSH,  etc.)  to  automate  the  maintenance  of  FORTRAN  and  RATFOR*  routines. 
EDIT  stores  the  source  code,  object  code,  and  load  module  for  a given 
program  as  ASC-cataloged  files  with  a user -specified  number  of  versions. 

To  use  EDIT  to  maintain  a program  the  user  must  first  catalog  a 
node  (i.e.,  filename)  in  the  ASC  tree -structured  file  catalog  system. 

The  user  may  then  use  EDIT  to  perform  a "creation  run"  (flagged  by  EDIT's 
OLDSRC  and  OLDOBJ  parameters)  to  establish  his  program  library.  EDIT  will 
catalog  three  nodes  beneath  the  user  supplied  node:  SRCLIB,  OBJLIB,  and 
LOADLIB,  for  the  source  code,  object  code,  and  load  module,  respectively. 
These  nodes  will  have  partial  access  control  and  full  son-add  control. x 
The  maximum  number  of  versions  of  the  files  is  specified  by  the  MXVR 
parameter  on  the  initial  macro  call. 

EDIT  will  catalog  files  containing  the  source  code,  object  code,  and 
load  module,  depending  on  the  values  of  the  EDIT  parameters  IEDIT  and 
CAT.  However,  these  files  will  not  be  cataloged  if  any  of  the  programs  called 
by  EDIT  end  with  a termination  code  which  indicates  a fatal  error.  Each 
time  a new  version  of  a file  is  cataloged, it  is  automatically  flagged  by 
the  system  as  the  version  to  be  used  by  the  next  EDIT  run.  When  the  user- 
specified  number  of  versions  has  been  cataloged,  the  oldest  version  will 
be  replaced  by  the  new  version.  Thus,  a programmer  may  update  and 
maintain  programs  by  simply  supplying  update  information  to  EDIT.  All  file 
manipulation  and  library  updat ing  are  managed  by  the  EDIT  macro. 


* 

Rational  FORTRAN  preprocessor,  see;  Kemighan  and  Plauger,  "Software 
Tools,"  Addison-Wesley  (1976).  Consult  DTNSRDC  Code  1845 , Numerical  Fluid 
Dynamics  Branch,  (202)  227-1933  for  local  modifications  to  RATFOR. 

▲ 

These  terms  are  used  to  define  specific  characteristics  of  a node. 

They  control  who  may  access  the  node  and  who  may  add  sons  beneath  the  node. 
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INPUT  TO  EDIT 


Input  to  EDIT  is  in  the  form  of  SMS  directives  which  may  either 
follow  the  EDIT  call  or  be  on  a file  named  by  the  EDIT  EDTINRJT  parameter. 
An  SMS  $OPTION  card  is  not  required,  as  one  is  automatically  supplied  by 
EDIT  (SOPTION  A,B,D,L*1).  If  the  user  chooses  to  override  the  default 
$OPTION  card,  the  A,  B,  and  D options  must  still  be  specified 
to  insure  that  all  libraries  will  be  properly  updated.  The  user  is  also 
cautioned  that  a deck  which  is  deleted  from  the  source  library  (SRCLIB) 
is  not  automatically  deleted  from  the  object  library  (OBJLIB) . This 
situation  seldom  arises,  but  may  be  remedied  by  using  CIFER  to  manually 
delete  the  object  code. 


EDIT  PARAMETERS 

The  format  of  the  EDIT  call  is  as  follows: 


FTVERS=(*)  ,SPACE=<  integer>  ,LNKOPT=(*),EDITLIST=  <name>  , 

LNKINPUT=<name> ,EDTiNPUT=<name> 

The  quantities  between  the  brackets  are  all  optional;  the  default 
values  are  underlined.  The  meaning  of  each  of  the  parameters  is  given 
below. 

PATH  Existing  pathname  of  program  to  be  edited. 

IF.DIT  1.  Perform  source  update  and  comnile. 

2.  Same  as  IF.DIT=1,  plus  update  object  library. 
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MXVR 

CAT 

0IJX3BJ 

OLDSRC 

DTYP 

RATFOR 

* 

SPACE 

EDITLIST 

LNK INPUT 
EDT INPUT 


3.  Same  as  IEDIT=2,  plus  build  a new  load  module. 

Number  of  versions  of  files  to  be  kept.  This  parameter 
is  meaningful  only  for  the  first  EDIT  run  having  CAT=YES. 
Command  to  catalog  new  files  if  the  run  is  successful. 
Indicates  whether  object  code  has  previously  been  cataloged  by 
EDIT.  Should  be  set  to  NO  the  first  time  EDIT  is  used 
with  IEDIT>2  and  CAT=YES.  Thereafter  the  default  value  of 
OLDCRJ=YES  may  be  used. 

Similar  to  OLDOBJ  except  that  it  applies  to  the  source  file; 
OLDSRC  should  be  set  to  NO  the  first  time  EDIT  is  run  with 
CAT=YES  (i.e.,  a "creation  run"). 

File  storage  device  desired.  This  parameter  may  be 
different  for  successive  runs,  but  is  meaningful  only  when 
CAT=YES. 

Instructs  EDIT  that  this  run  updates  decks  written  in  RAT- 
FOR. Each  RATFOR  program  must  be  preceded  by  a card  with  a 
sharp  sign  in  column  1 to  initiate  RATFOR  processing. 

See  FTN  and  LNK  macros  for  FORTRAN  and  LINKAGE  EDITOR 
options.  System  default  options  will  be  supplied  if  these 
parameters  are  omitted. 

Identical  to  FTN  SPACE  parameter.  System  default  will  be 
supplied  when  SPACE  is  omitted. 

Used  to  name  print  file.  If  this  parameter  is  omitted,  the 
print  file  name  will  be  EDIT.PRT  and  will  be  printed 
automatically. 

Names  an  optional  input  file  to  the  LINKAGE  EDITOR.  This 
file  is  required  only  if  the  user  desires  to  supply  routines 
to  the  LINKAGE  EDITOR  which  exists  on  external  libraries. 

Name  of  file  containing  the  SMS  input  deck  to  EDIT.  If 
this  parameter  is  omitted,  it  is  assumed  that  SMS  directives 
immediately  follow  the  EDIT  call  card. 


EXAMPLES 


ESTABLISHING  A PROGRAM  LIBRARY 


/ JOB 

/ MAC  ABC  MACRO, DOD/NAVY/NSRDC/MBRAPI /MACLIB 
/ LIMIT  BAND«J0 

/ EDIT  EXAMPLC/RATH/NAMe,flLD0BjBN0,0lO8RC«Ne,IEDIT«? 
SM0D3ET  EXAMPLE, USERaJOEUBER 

•DEC*  EXMAlN,LANGaPORTRAN,uSERajeEUSER,ACTIONtADD 
program  exmain 

c 

c • main  PROGRAM  for  EXAMPLES 

c 

X a 3. 

Y ■ 2. 

Z ■ X ♦ Y 

CALL  EX8UB(X,Y,Z) 

STOP 

ENO 

/ EOJ 


This  example  establishes  a source  library  and  an  object  library 
beneath  the  node  "EXAMPLE/PATH/NAME",  a node  which  was  previously 
cataloged  by  the  user.  The  MACASG  statement  assigns  the  author's  MACRO 
library  (which  contains  EDIT)  to  the  user's  job.  IEDIT  is  set  to  2 to 
inhibit  load  module  creation,  since  the  main  program  calls  a subroutine 
not  yet  in  the  library.  The  OLDOBJ  and  OLDSRC  parameters  are  both  set 
to  NO  to  indicate  that  neither  OBJECT  nor  SOURCE  libraries  have  previouslv 


been  cataloged  for  this  particular  program  node. 
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ADDING  A DECK  TO  AN  EXISTING  LIBRARY 


/ JOB 

/ macaSG  MACRO, DOD/NAVY/NSRDC/mORAPi/maCLIB 
/ L I M I T BANDOO 

/ CD  I T EXAMPLE/PATH/NAME,RATF0R«YE8 
SHODSCT  UPDATE1 ,U3ER«J0CUSER 

•DECK  E X3UB , L ANG«R ATFOR, USER* J8EU8ER, ACTION* ADD 
C THIS  CARD  FLAGS  RATF8R  DECK 

SUBROUTINE  EXSUB  ( X # Y # Z ) 

SUBROUTINE  FOR  EXAMPLES 

R ■ X*X*Y*Y 

IF  (R  .EG.  0.)  RETURN  $ NOTE  THAT  THE  SHARP 

IF  (R  , GE « Z)  p SIGN  ALLOWS  The  USER  TO  C0MME 

[ n M8RE  FREELY 

Z ■ SIN(Z) 

X ■ 0. 

V a 0, 

1 

ELSE  Z « C08CZ) 

RETURN 
END 
/ EOJ 


This  example  adds  a deck  to  the  program  library  created  in  the 
first  example.  The  RATFOR=YES  option  is  used  to  inform  EDIT  that  this 
run  contains  references  to  DECKS  which  are  written  in  RATFOR.  The  card 
with  the  sharp  sign  in  column  1 is  a flag  to  the  RATFOR  processor  that 
RATFOR  code  follows.  FORTRAN  and  RATFOR  codes  may  be  freely  interspersed, 
since  the  END  card  of  each  RATFOR  program  turns  the  RATFOR  processor  off. 
The  default  EDIT  option  (IEDIT=3)  is  used  in  this  case  to  allow  a load 
module  to  be  built,  since  this  run  supplies  the  subroutine  which  was 
missing  in  the  first  example. 
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MAKING  A CORRECTION  TO  AN  EXISTING  PROGRAM 


r 


/ JOB 

/ MAC ASG  MACRO, 00D/NAVY/NIR0C/M0RAP1 /MACLI8 
/ LIMIT  BAND* JO 
/ EDIT  EXAMPLE/PATH/NAME 
IM008ET  UPOATE2,U8ER»JANEUSER 
•DECK  EXMAIN,U8ER«JANEU8ER 
IREPIACE  7 
Z«X*Y 

/ E8J 


This  example  shows  how  the  user  would  replace  line  7 of  the  main 
program  of  the  first  example  with  the  desired  line,  Z = X*Y.  Since  the 
default  EDIT  option  is  used  (IEDIT=3) , all  libraries,  including  the  load 
module,  would  reflect  the  change. 


EXECUTING  .AN  EXISTING  PROGRAM 


/ JOB 

/ ASG  8YB.LM0D,EXAMPLE/PaTH/NAME/l0ADLIB,U8E*SH9 
/ PXQT 
/ EOJ 


This  example  shows  how  to  execute  the  program  developed  in  the 
previous  three  examples.  Since  the  load  module  was  assigned  with  the 
access  name  SYS.LMOD,  the  FXQT  macro  may  be  used  to  accomplish  a standard 
FORTRAN  execution. 
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DTNSRDC  ISSUES  THREE  TYPES  OF  REPORTS 

(1)  DTNSRDC  REPORTS,  A FORMAL  SERIES  PUBLISHING  INFORMATION  OF 
PERMANENT  TECHNICAL  VALUE,  DESIGNATED  BY  A SERIAL  REPORT  NUMBER 

(2)  DEPARTMENTAL  REPORTS,  A SEMIFORMAL  SERIES,  RECORDING  INFORMA 
TION  OF  A PRELIMINARY  OR  TEMPORARY  NATURE,  OR  OF  LIMITED  INTEREST  OR 
SIGNIFICANCE,  CARRYING  A DEPARTMENTAL  ALPHANUMERIC  IDENTIFICATION 

(3)  TECHNICAL  MEMORANDA,  AN  INFORMAL  SERIES,  USUALLY  INTERNAL 
WORKING  PAPERS  OR  DIRECT  REPORTS  TO  SPONSORS,  NUMBERED  AS  TM  SERIES 
REPORTS;  NOT  FOR  GENERAL  DISTRIBUTION 


